home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_kdelibs.idb / usr / freeware / kde / include / knotebook.h.z / knotebook.h
Encoding:
C/C++ Source or Header  |  1999-01-26  |  11.3 KB  |  400 lines
  1. /*  This file is part of the KDE Libraries
  2.     Copyright (C) 1998 Thomas Tanghus (tanghus@earthling.net)
  3.  
  4.     This program is free software; you can redistribute it and/or
  5.     modify it under the terms of the GNU General Public
  6.     License as published by the Free Software Foundation; either
  7.     version 2 of the License, or (at your option) any later version.
  8.  
  9.     This program is distributed in the hope that it will be useful,
  10.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.     General Public License for more details.
  13.  
  14.     You should have received a copy of the GNU Library General Public License
  15.     along with this library; see the file COPYING.LIB.  If not, write to
  16.     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17.     Boston, MA 02111-1307, USA.
  18. */  
  19.  
  20. #ifndef __KNOTEBOOK_H
  21. #define __KNOTEBOOK_H
  22.  
  23. #ifndef KDE_KDIRECTIONBUTTON
  24. #define KDE_KDIRECTIONBUTTON
  25. #endif
  26. #ifndef KDE_KWIZARD
  27. #define KDE_KWIZARD
  28. #endif
  29. #ifndef KDE_KTABBAR
  30. #define KDE_KTABBAR
  31. #endif
  32.  
  33. #include <ktabbar.h>
  34. #include <kwizard.h>
  35.  
  36. struct KNoteBookProtected;
  37.  
  38. /**
  39. * KNoteBook is a tabbed dialog where each tab can have multiple pages.
  40. * The widget has the advantages of both KTabCtl and QTabDialog plus some more.
  41. *
  42. * Features:
  43. *
  44. * - Multiple pages per tab with previous/next button and optional arrow buttons in the title..
  45. *
  46. * - An optional popup menu which takes you to a specific page in a specific section (tab).
  47. *
  48. * - Easy additions of Ok, Cancel, Default and Help buttons.
  49. *
  50. * - Automatic resizing/repainting/repositioning of buttons. Not like QTabDialog where
  51. * there is always an Ok button.
  52. *
  53. * - Scrollable tab bar.
  54. *
  55. * - Can be used as both modal/non-modal dialog and a child widget.
  56. *
  57. * @short KNoteBook
  58. * @author Thomas Tanghus <tanghus@earthling.net>
  59. * @version 0.2
  60. */
  61. class KNoteBook : public QWidget
  62. {
  63.         Q_OBJECT
  64. public:
  65. /**
  66. * Constructs a KNoteBook.
  67. *
  68. * A modal notebook can be created like this:
  69. * <pre>
  70. * KNoteBook *nb = new KNoteBook(this, "notebook", true);
  71. * connect(nb, SIGNAL(okclicked()), SLOT(nb->hide()));
  72. * connect(nb, SIGNAL(okclicked()), SLOT(readNewInput()));
  73. * </pre>
  74. *
  75. * A very simple program where the main window is a KNoteBook with one tab
  76. * and one page inserted could look like this:
  77. * <pre>
  78. * int main(int argc, char **argv)
  79. * {
  80. *   KApplication a(argc,argv,"knotebooktest");  // create an application object
  81. *   KNoteBook *nb = new KNoteBook(); // create the notebook
  82. *   nb->setCancelButton();           // add a Cancel button and connect it to the quit() slot
  83. *   QObject::connect( nb, SIGNAL(cancelclicked()), &a, SLOT(quit()) );
  84. * 
  85. *   QTab *tab = new QTab;            // create a QTab to hold the tab data
  86. *   tab->label = "A tab";
  87. *   tab->enabled = true;
  88. *   nb->addTab( tab );
  89. *   QLabel *l = new QLabel(nb);
  90. *   l->setAlignment(AlignCenter);
  91. *   l->setText("This is a QLabel as a page");
  92. *   l->setMinimumSize(400, 300);
  93. *   KWizardPage *p = new KWizardPage;
  94. *   p->w = l;
  95. *   p->title.setNum("A page title");
  96. *   p->enabled = true;
  97. *   nb->addPage( p );
  98. * 
  99. *   a.setMainWidget(nb);
  100. *   nb->adjustSize();
  101. *   nb->show();
  102. *   return a.exec();
  103. * }
  104. </pre>
  105. * @see QDialog::QDialog
  106. *
  107. * @param parent The parent of the notebook.
  108. *
  109. * @param name The internal name.
  110. *
  111. * @param modal If modal is true the notebook wil become a modal dialog.
  112. *
  113. * @param f Window flags.
  114. */
  115.         KNoteBook(QWidget *parent = 0, const char *name = 0, bool modal = false, WFlags f = 0);
  116. /**
  117. * Destructor
  118. */
  119.         KNoteBook::~KNoteBook();
  120. /**
  121. * Adds a new tab to the notebook and creates a new @ref KWizard to hold the pages.
  122. * The tabs are numbered from 0 to n where 0 is the tab first added and n is the
  123. * tab last added. if you add 4 tabs the last tab will be number 3. 
  124. * Subsequent calls to @ref addPage will add pages to this tab  until a new call to addTab().
  125. *
  126. * @param tab The QTab containing the tab data.
  127. *
  128. * @param p The optional KWizardPage containing the page data.If 'p' is not 0 it
  129. * will be added as a new page.
  130. * This is equivalent to @ref addPage (p);
  131. * @return Returns the id of the new tab.
  132. */
  133.         int addTab(QTab *tab, KWizardPage *p = 0L);
  134. /**
  135. * Adds a new page to the last added tab.
  136. * The pages are numbered from 0 to n where 1 is the page first added and n is the
  137. * page last added. Subsequent calls to @ref addPage will add pages to the last added
  138. * tab until a new call to addTab().
  139. *
  140. * @param p The KWizardPage containing the page data..
  141. *
  142. * @return Returns the id of the new page. The id is relative to the KWizard, NOT
  143. * the KNoteBook.
  144. */
  145.         int addPage(KWizardPage *p);
  146. /**
  147. * Turn to another tab. This method calls @ref showSection to show the corresponding KWizard.
  148. *
  149. * @param tab The tab to turn to
  150. */
  151.         void gotoTab(int tab);
  152.  
  153.         QSize sizeHint() { return minimumSize(); };
  154.         void adjustSize() { resize(sizeHint()); };
  155.  
  156. /**
  157. * Adds a Cancel button to the bottom of the dialog. The text will be a translated
  158. * version of the string '&Cancel' thereby giving it the shortcut key 'c'.
  159. * If any buttons are added a space will be created at the bottom of the dialog
  160. * to fit the buttons. When clicked the button will emit the @ref cancelclicked signal.
  161. * @see KLocale#translate
  162. */
  163.         void setCancelButton();
  164. /**
  165. * Adds a Cancel button to the bottom of the dialog.
  166. * @param text A user supplied text to write to the button.
  167. */
  168.         void setCancelButton(const char *text);
  169. /**
  170. * Adds a Default button to the bottom of the dialog. The text will be a translated
  171. * version of the string '&Default' thereby giving it the shortcut key 'd'.
  172. * If any buttons are added a space will be created at the bottom of the dialog
  173. * to fit the buttons. When clicked the button will emit the @ref defaultclicked signal.
  174. * @see KLocal::translate
  175. */
  176.         void setDefaultButton();
  177. /**
  178. * Adds a Default button to the bottom of the dialog.
  179. * @param text A user supplied text to write to the button.
  180. */
  181.         void setDefaultButton(const char *text);
  182. /**
  183. * Adds a Help button to the bottom right of the dialog. The text will be a translated
  184. * version of the string '&Help' thereby giving it the shortcut key 'h'.
  185. * If any buttons are added a space will be created at the bottom of the dialog
  186. * to fit the buttons. When clicked the button will emit the @ref helpclicked signal.
  187. */
  188.         void setHelpButton();
  189. /**
  190. * Adds a Help button to the bottom of the dialog. This button will generate the
  191. * signal @ref helpclicked where the int is the page to which the help was requested.
  192. * @param text A user supplied text to write to the button.
  193. */
  194.         void setHelpButton(const char *);
  195. /**
  196. * Adds an Ok button to the bottom right of the dialog. The text will be a translated
  197. * version of the string '&Ok' thereby giving it the shortcut key 'o'.
  198. * If any buttons are added a space will be created at the bottom of the dialog
  199. * to fit the buttons. When clicked the button will emit the @ref okclicked signal.
  200. */
  201.         void setOkButton();
  202. /**
  203. * Adds an Ok button to the bottom of the dialog. This button will generate the
  204. * signal @ref okclicked where the int is the page to which the help was requested.
  205. * @param text A user supplied text to write to the button.
  206. */
  207.         void setOkButton(const char *);
  208. /**
  209. * Get Ok button.
  210. * @return Returns the Ok buttonwidget or 0L if no button is added.
  211. */
  212.         QButton *getOkButton();
  213. /**
  214. * Get Cancel button.
  215. * @return Returns the Cancel buttonwidget or 0L if no button is added.
  216. */
  217.         QButton *getCancelButton();
  218. /**
  219. * Get Default button.
  220. * @return Returns the Default buttonwidget or 0L if no button is added.
  221. */
  222.         QButton *getDefaultButton();
  223. /**
  224. * Get Help button.
  225. * @return Returns the Help buttonwidget or 0L if no button is added.
  226. */
  227.         QButton *getHelpButton();
  228. /**
  229. * Let direction buttons reflect page.
  230. * @param state If state is true the direction buttons (Previous and Next) will have the
  231. * title of the corresponding page.
  232. * @see #directionsReflectsPage
  233. */
  234.         void setDirectionsReflectsPage(bool state);
  235. /**
  236. * @return Returns whether the direction buttons reflects the title of the corresponding page.
  237. *
  238. * @see #setDirectionsReflectsPage(bool state)
  239. */
  240.         bool directionsReflectsPage();
  241. /**
  242. * En/Disable the popup menu.
  243. * @param state If state is true a menu containing the pages in the wizard
  244. * will popup when the user RMB-clicks on the page-title.
  245. */
  246.         void setEnablePopupMenu(bool state);
  247. /**
  248. * Returns whether the menu is enabled or not.
  249. * @return 'true' if the menu is enabled, otherwise 'false'.
  250. */
  251.         bool enablePopupMenu();
  252. /**
  253. * Get the popup menu.
  254. * @return Returns the handle of the popup menu.
  255. */
  256.         QPopupMenu *getMenu();
  257. /**
  258. * En/Disable the arrowbuttons.
  259. * @param state If state is true two arrows will appear to the right of the title.
  260. * @see #enableArrowButtons
  261. * @see KWizard#setEnableArrowButtons.
  262. */
  263.         void setEnableArrowButtons(bool state);
  264. /**
  265. * @return Returns whether the arrow buttons are enabled or not.
  266. * @see #setEnableArrowButtons
  267. * @see KWizard#enableArrowButtons.
  268. */
  269.         bool enableArrowButtons();
  270. /**
  271. * Returns the handle of the tab bar.
  272. */
  273.         KTabBar *getTabBar();
  274. /**
  275. * Returns the number of tabs in the notebook.
  276. */
  277.         int numTabs();
  278. /**
  279. * En/Disable a tab in the notebook. If a tab is disabled it is not selectable
  280. * from the tab bar. If the user reaches a disabled tab by traversing through
  281. * the pages the notebook will jump to the next enabled tab.
  282. */
  283.         void setTabEnabled(int tab, bool state);
  284. /**
  285. * @return Returns whether the tab is enabled or not.
  286. * @see #setTabEnabled
  287. */
  288.         bool isTabEnabled(int tab);
  289. /**
  290. * En/Disable a page in a section (tab) in the notebook
  291. * @see KWizard#setPageEnabled
  292. */
  293.         void setPageEnabled(int tab, int page, bool state);
  294. /**
  295. * @return Returns whether a page in a section (tab) is enabled or not.
  296. * @see #setTabEnabled
  297. */
  298.         bool isPageEnabled(int tab, int page);
  299.  
  300. signals:
  301. /**
  302. * This signal is emitted when the user clicks on the Ok button.
  303. */
  304.         void okclicked();
  305. /**
  306. * This signal is emitted when the user clicks on the Cancel button.
  307. */
  308.         void cancelclicked();
  309. /**
  310. * This signal is emitted when the user clicks on the Default button.
  311. */
  312.         void defaultclicked(int);
  313. /**
  314. * This signal is emitted when the user clicks on the Help button.
  315. * The int is the page which was showing when help was requested.
  316. * @see #setHelpButton
  317. */
  318.         void helpclicked(int);
  319.  
  320. protected slots:
  321. /**
  322. * Called by @ref gotoTab to show the appropriate KWizard.
  323. */
  324.         void showSection(int);
  325. /**
  326. * If the menu is enabled by @ref enablePopupMenu this method will let the menu
  327. * popup at 'pos'.
  328. * @internal
  329. */
  330.         void popupMenu(QPoint pos);
  331. /**
  332. * @internal
  333. */
  334.         void menuChoice(int);
  335. /**
  336. * @internal
  337. */
  338.         void menuChoiceRedirect(int);
  339. /**
  340. * @internal
  341. */
  342.         void directionButton(bool, bool);
  343. /**
  344. * @internal
  345. */
  346.         void okClicked();
  347. /**
  348. * @internal
  349. */
  350.         void cancelClicked();
  351. /**
  352. * @internal
  353. */
  354.         void defaultClicked();
  355. /**
  356. * @internal
  357. */
  358.         void helpClicked();
  359. /**
  360. * @internal
  361. */
  362.         void tabScroll( ArrowType );
  363.  
  364. protected:
  365. /**
  366. * @internal
  367. */
  368.         void init();
  369. /**
  370. * @internal
  371. */
  372.         void resizeEvent(QResizeEvent *);
  373. /**
  374. * @internal
  375. */
  376.         void paintEvent(QPaintEvent *);
  377. /**
  378. * @internal
  379. */
  380.         void setSizes();
  381. /**
  382. * @internal
  383. */
  384.         QSize childSize();
  385.  
  386. /**
  387. * @internal
  388. */
  389.         KNoteBookProtected *pnote;
  390. /**
  391. * @internal
  392. */
  393.         QList<KWizard> *sections;
  394. };
  395.  
  396. #endif __KNOTEBOOK_H
  397.  
  398.  
  399.  
  400.